Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / byte0387.arc / DAWSON.ARC / SIMPP.DOC < prev next >

Wrap

Text File | 1985-07-12 | 14.5 KB | 355 lines

/************************************************************************* |===================================================================| | SIMPP = Simple IMage Processing Package. | | | | Copyright (c) 1987, Benjamin M. Dawson | | Edit 1.2 : Jan. 30, 1987 | | This package may be freely copied, modified, and used for non- | | commercial purposes. No guarantee is made that this code is | | correct or suitable for any purpose. This notice, including the | | copyright notice, must appear in all copies and modifications. | |===================================================================| I. Introduction SIMPP (Simple IMage Processing Package) is a model image processing package that demonstrate some important and basic algorithms in image processing. It is written in "standard" (K&R) C and has been compiled and tested on: (1) an IBM Personal Computer/AT using the Computer Innovations Inc. C compiler (Big model) and an Imaging Technology Inc. Series 100 frame memory. (2) A DEC VAX 11/750 computer using the Berkeley Unix (4.2) C compiler an Adage 3000 (Ikonas) image processor. Please see my article in the March, 1987 edition of BYTE magazine ("An Introduction to Image Processing Algorithms") for details on the package and algorithms. II. Hardware Requirements SIMPP assumes that you have simple image processing hardware on your computer that can acquire, store, access, and display images with 8 bits of grey-level intensity. In particular, this hardware must be able to: 1. Acquire and store a single picture (a "frame") from an image source (e.g. TV camera, disk, etc.), with an intensity resolution of 8 bits. This will give a pixel values ranging from 0 to 255. Intensities above 255 are clipped to 255, and intensities below 0 are clipped to 0. These data are put into the "image memory". 2. Access (read and write) this image memory on a pixel-by-pixel basis, as if the picture values were stored in a large matrix of XSIZE columns by YSIZE rows. I suggest a minimum size of YSIZE = 256 rows and XSIZE = 256 columns. The pixels are organized by "video" coordinates: x values increase from left to right, and y values increase from top to bottom. Thus coordinate (0,0) is at the top,left of the image and (XSIZE-1,YSIZE-1) is the bottom,right point in the image. The image points must be in normal order rather than in interlace or any other order. 3. Display the pixel values on an RGB or monochrome television monitor or other display device (e.g., EGA, printer, etc.). If your hardware has transformation tables ("Look-Up Tables" or LUTs) for transforming the output pixel values before they are displayed, the SIMPP package can use these tables. Normally these LUTs map a single (monochrome) pixel value to a red, green, blue triple of values. This allows image memory values to be displayed as arbitrary colors (pseudo-color) III. Software Setup In order to use SIMPP, you will need to: 1. Modify the "simpp.h" header to define your hardware to the software. 2. Write a set of interface routines that access your hardware. 3. Deal with porting the software to your machine. 4. Compile and link the software. 1. Values in the header "simpp.h" specify the hardware you are using to the SIMPP software. Here is an annotated copy of the header, showing items you may want to modify (Set off by !! at the beginning of the line): /*********************************************\ * * * simpp.h = Include file for SIMPP * * For Simple IMage Processing Package. * * Copyright (c) 1987, Benjamin M. Dawson. * * Edit Version: 1.1 : Jan-29-87 * * * \*********************************************/ !! (1) The VOID definition indicates that no useful value is returned from !! by the function. This helps document the function and mollifies some !! automatic code checkers. /* Type definitions */ #ifndef VOID /* VOID: No useful return from function */ #define VOID #endif !! (2) These definitions specify image memory size and structure. /* Storage definitions. May need to be changed for your hardware!! */ !! Each pixel (individual image point) is stored in a 8-bit byte, !! even if the hardware acquires fewer bits. For example, if you !! have 6-bit pixels, they still must occupy a byte. A pixel can !! occupy more than a byte (a short, for example), but you might !! run out of heap space (internal buffers) on a "small" machine. !! Try not to change this item. #define PIXEL unsigned char /* Pixel type must be an 8-bit value! */ !! The size of pixel. This is for 8-bit values. If your pixels have !! fewer bits, change accordingly. For example, for 6-bit pixels, !! define PIXEL_SIZE to be 64. #define PIXEL_SIZE 256 /* Size of pixel */ !! The minimum pixel value. Leave this at 0, if you can. #define MINPIX (PIXEL)0 /* Minimum pixel value */ !! The maximum pixel value is automatically computed. DON'T CHANGE THIS! #define MAXPIX (PIXEL)(PIXEL_SIZE-1) /* Maximum pixel value */ !! Starting index for the image memory. Leave these at 0, if you can. #define XSTART 0 /* Starting image memory X address */ #define YSTART 0 /* Starting image memory Y address */ !! Change this to indicate the horizontal size of your image memory. #define XSIZE 512 /* Horizontal (row) size of image memory */ !! Change this to indicate the vertical size of your image memory. #define YSIZE 480 /* Vertical (column) size of image memory */ !! Automatic definitions. DON'T CHANGE THESE! #define XEND XSIZE-1 /* Last horizontal pixel address */ #define YEND YSIZE-1 /* Last vertical pixel address */ !! (3) Define CHECK if you want software checking of arguments ranges. !! A good idea for debugging! /* Option switches */ #define CHECK /* Define CHECK for bounds checking */ !! (4) These define return values for error reporting. /* Return values */ #define ERROR -1 /* Error return */ #define OK 0 /* Return OK */ !! (5) These define the maximum kernel size for the convolution, and values !! specifying how the output of the convolution will be processed. /* Convolution switches */ !! This specifies the maximum kernel size. Used for checking arguments. #define MAX_KERNEL_SIZE 8 /* Maximum size of kernel */ !! These specify how to process the result of the convolution. #define SIGNED 0 /* Don't change convolution output */ #define POSITIVE 1 /* Output + values only. - set to 0 */ #define NEGATIVE 2 /* Set + values to 0, output - of - values */ #define ABSOLUTE 3 /* Output absolute values */ !! (6) External procedure declarations. Don't change. /* External declarations */ extern PIXEL read_pixel(); extern PIXEL read_LUT(); !! (7) Change these values to specify the hardware you are using. /* CPU and image memory (image processor) specific definitions */ !! MEMSIZE is the largest possible buffer you can allocate in your !! CPU. This size limits the size of the geometric transformations !! and some other operations. For the IBM AT or PC, with CII Big this !! is 2^16-20, as shown below. Other CPUs and operating systems may !! allow a larger value. #define MEMSIZE 65516L /* Size of largest buffer for CII Big model */ !! The output values from the convolution routine are scaled (divided !! by using a shift function. Some machines fill with the sign bit on !! a right shift (divide by 2) and others don't. Define this if your !! machine does NOT sign fill on right shift. #undef NO_SIGN_FILL /* Define if CPU does NOT fill with sign */ /* bits on a right shift (see convolution) */ !! If your image memory (image processing board) has output LUTs that allow !! a pixel to be transformed into a red,green,blue triple of values for !! display on a color monitor, then define LUTS to use these LUTs. If you !! define this and don't have LUTs, the only damage is larger code. #define LUTS /* Define LUTS if you have output LUTS */ #ifdef LUTS !! These select an output LUT for modification. #define RED 1 /* Select RED LUT */ #define GREEN 2 /* Select GREEN LUT */ #define BLUE 3 /* Select BLUE LUT */ #endif /* ================ End of simpp.h ================ */ 2. You must write a set of "interface" routines that link the SIMPP package with your image memory or image processing hardware. These routines are gathered in the "siminter.c" module. The interface routines are specified below, but not given in this package, as they will be machine specific. A "dummy" version of "siminter.c" is provided to help you write a version specific to your hardware. Primitives: int sim_open() Opens and initializes the imaging hardware. Returns ERROR or OK. int sim_close() Closes the imaging hardware. Returns ERROR or OK. VOID acquire() Acquires one image into the image memory and returns when done. PIXEL read_pixel(x,y) int x,y; Returns the value of the pixel in location (x,y) of the image memory. VOID write_pixel(x,y,z) int x,y; PIXEL z; Writes a new pixel value, z, to location (x,y) in the image memory. VOID write_LUT(color,loc,value) int color,loc; PIXEL value; Set the location specified by loc in the look-up table specified by color to value. If you don't have (or use) LUTs, this should be a dummy routine. 3. Porting the software to your machine. I have tried to make the SIMPP package as portable as possible, sometimes at the expense of performance. Hopefully this will make it easy to port to your particular compiler, CPU, and image processing hardware. Some notes: -- Differences in image processing hardware and host CPU are indicated by #define's in "simpp.h", as noted above. You might have to add some #defines for your hardware and compiler. -- You will probably have a lot of trouble if your machine does not have an 8-bit byte (e.g. a PDP-8). Then again, you probably don't have a C compiler! -- Your C compiler must be reasonably complete. It if follows the K&R standard, you should have no problems. Data types used include: unsigned char char int (assumed to be short where necessary) long (cast to long where necessary) double -- Elements of the "standard" C I/O library used include: "stdio.h" malloc() and free() printf(), fprintf(), and scanf() open(), read(), write() exit() You may have to change these calls to use your compiler's versions. For example, under some versions of Whitesmiths' C on the PDP-11, printf() becomes putfmt(), and the %d field specifier becomes %i. malloc: It is assumed that malloc() takes an argument of type: unsigned int. If your C library requires this argument to be a long and your type int is not equal to a long, then calls to malloc must be changed. If you don't have malloc() and free(), then you can change the code to use static buffers. You may not be able to use the geometric transforms, as they malloc large buffers. open: The arguments to open vary from library to library. This distribution shows them as appropriate for Berkeley 4.2 Unix. You may have to change the READ_ONLY and WRITE_ONLY definitions, and reduce the number of arguments to open() from 3 to 2 (drop the 0777 argument). exit: The argument to exit indicates what kind of error is returned to the system. The arguments are defined for Berkeley 4.2 Unix in this distribution. You may have to change them to something appropriate for your system. -- If your compiler does not use ASCII to encode characters, you may have to modify the matches() routine in "simtest.c" -- All routine names are different in the first 8 characters. You may have to these and/or internal variable names to meet the requirements of your compiler. If your compiler only has 6 character names, you may have to change the subroutine names. 4. Compiling and linking the software. This SIMPP distribution (version 1.1 -- January 1987) consists of the following files: makefile = A Unix-style file for making the test program. readme = A short note as to the contents of the directory. simarea.c = Area image processing functions. simgeo.c = Geometric image processing functions. siminter.c = Model hardware interface routines. simmeas.c = Image measurement functions. simpoint.c = Point image processing routines. simpp.doc = This document. simpp.h = Hardware definition header file. simsubs.c = Subroutines for test program. simtest.c = Test program. simutil.c = Utility programs. The C modules (.c) are compiled in the normal fashion and linked with your main program. The test program ("simtest.c") contains a main() call, so you can link with this for a executable program. The "makefile" can be used or modified to automatically build the software and test program. If you use the test program (simtest.c), the gaussian burn function (in simsubs.c) requires the calculation of an exponential. This is usually covered by the inclusion of a math library. Table 1 in the BYTE article contains a list of functions in each module, except for simtest.c and simutil.c. IV. Testing the software. A rather extensive test program, "simtest.c" is included. This uses a menu to select operations and also has an automatic test sequence. You may want to use this program as a starting point for your program, and you certainly should use it to see that you have ported and compiled everything correctly. The test program was used to process some of the images in the BYTE article. V. Notes The individual files in this package are separated by the special character sequence: /* <-- FILE BREAK --> */ This helps separate the files if they are concatenated during distribution. I am delighted to hear from you by letter or electronic mail about the plusses and problems of SIMPP, and any corrections and additions. I cannot be your telephone consultant -- I'm hard to reach and very busy (who isn't!). If you wish to use this package in a product, reprint, distribute, or use it in a some commercial way, please contact me about licensing. Happy image processing! Dr. Ben Dawson E10-120 M.I.T. home: 89 Overbrook Drive. 79 Amherst St. Wellesley, MA 02181 Cambridge MA, 02139 Tel. (617) 253-5700 ARPA net: BMD@OZ.AI.MIT.EDU /* ================ End of simpp.doc ================ */ /* <-- FILE BREAK --> */